IDLffVideoRead
The IDLffVideoRead class can be used to open video files in a variety of formats and read out frames of video, samples of audio, and packets of data.
The process for reading a video file is:
- Create the object and open associated video with IDLffVideoRead::Init.
- Use IDLffVideoRead::GetNext in a loop to increment through the file.
- Destroy the object and close the file with IDLffVideoRead::CleanUp.
For more information on video, please see the Creating Video topic.
Note: Frame counts may vary slightly depending on the method used to obtain the count. Variabilities in timestamps and video standards, discontinuities in the videos themselves, or differences in the types of frames may influence the apparent frame count.
Note: IDLffVideoRead is not available with the IDL Virtual Machine.
Superclasses
None.
Creation
See IDLffVideoRead::Init
Methods
This class has the following methods:
In addition, this class inherits the methods of its superclasses (if any).
Examples
The following example uses a NASA video displaying the coronal mass ejection (CME) event of Aug. 31, 2012, available online (see Resources and References, below) or in the \examples\data directory of your IDL installation.
CME.mp4 video courtesy NASA's Solar Dynamics Observatory (SDO)and Solar Heliospheric Observatory (SOHO).
PRO video_read_example2
file = FILEPATH('CME.mp4', SUBDIRECTORY=['examples','data'])
oVid = IDLffVideoRead(file)
; Open up an image window, with no data for now
img = IMAGE(BYTARR(2,2), /NODATA)
; Get the next packet of data from the file,
REPEAT BEGIN
data = oVid->GetNext(TYPE=type)
; If we got a frame of video, display it.
IF type EQ 1 THEN img.SetData, data
; Keep going until we reach the end of the file.
; Note: End of file is where TYPE=-1.
ENDREP UNTIL type EQ -1
img.CLOSE
END
IDLffVideoRead::Init
Initializes the video read object.
Syntax
Result = IDLffVideoRead([Filename], /VERBOSE )
or
Result = OBJ_NEW('IDLffVideoRead' [, Filename], /VERBOSE )
Return Value
When this method is called indirectly, as in the previous syntax, the return value is an object reference to the newly-created object.
When called directly within a subclass Init method, the return value is 1 if initialization was successful, or zero otherwise.
Arguments
Filename
An optional string that specifies the full path and name of the video file (container format) to read. If you do not specify a filename, IDL will still create the object which can be used with the ::GetCodecs or ::GetFormats methods.
Keywords
VERBOSE
By default, if the video file contains any video or audio codecs that are not supported, then IDL will quietly ignore these codecs and continue to open the file. Set the VERBOSE keyword to force IDL to issue informational messages when it encounters any unsupported codecs.
IDLffVideoRead::GetCodecs
This method returns the list of codecs supported by IDLffVideoRead.
Tip: You can call IDLffVideoRead::GetCodecs as a static method, without needing to create an IDLffVideoRead object. For example:
print, IDLffVideoRead.GetCodecs()
Syntax
Result = Obj.[IDLffVideoRead::]GetCodecs([/LONG_NAMES] [, /AUDIO,] [, /VIDEO])
or, calling as a static method:
Result = IDLffVideoRead.GetCodecs([/LONG_NAMES] [, /AUDIO,] [, /VIDEO])
Return Value
Returns an array of strings listing the supported video formats.
Arguments
None
Keywords
LONG_NAMES
Set this keyword to return longer, more descriptive names.
AUDIO
Set this keyword to output only audio codecs.
VIDEO
Set this keyword to output only video codecs.
IDLffVideoRead::GetNext
Continue to decode the video file until one of the decoders yields a result.
Syntax
Result = Obj.[IDLffVideoRead::]GetNext(/AUDIO, /DATA, ONLY_STREAM=value, STREAM=variable, TYPE=variable, TIME=variable, /VERBOSE, /VIDEO)
Return Value
Returns the decoded data: a [3, w, h] array of bytes for a frame of video (with w width and h height in pixels); a [c, n] array of integers for audio (with c channels and n samples); or an array of bytes for streamed data.
Arguments
None
Keywords
AUDIO
Set this keyword to indicate that only audio data should be returned.
DATA
Set this keyword to indicate that only auxiliary data should be returned.
ONLY_STREAM
Set this keyword to the index value of the stream of interest so that IDL returns only that stream.
STREAM
Set this keyword to a named variable to specify the index value of the data stream you want to retrieve (see the ::GetStreams method for information on retrieving streams indices).
TYPE
Set this keyword to a named variable to capture an integer value representing the data type: 0=unknown, 1=video, 2=audio, 3=data, -1=EOF (end of file).
TIME
Set this keyword to a named variable to capture the data's place in the file, in seconds from the beginning.
VERBOSE
By default, any warnings or non-fatal errors will be quietly ignored. Set the VERBOSE keyword to issue informational messages for these warnings.
VIDEO
Set this keyword to indicate that only video data should be returned.
Note: One, two, or more of DATA, AUDIO, and VIDEO may be set to filter on those types. If none are set, all are assumed.
IDLffVideoRead::GetFormats
This method returns the list of formats supported by IDLffVideoRead.
Tip: You can call IDLffVideoRead::GetFormats as a static method, without needing to create an IDLffVideoRead object. For example:
print, IDLffVideoRead.GetFormats()
Syntax
Result = Obj.[IDLffVideoRead::]GetFormats([/LONG_NAMES])
or, calling as a static method:
Result = IDLffVideoRead.GetFormats([/LONG_NAMES])
Return Value
Returns an array of strings listing every supported format.
Arguments
None
Keywords
LONG_NAMES
Set this keyword to return longer, more descriptive names.
IDLffVideoRead::GetMetadata
Retrieves metadata values corresponding to the given key, such as 'title', 'copyright', 'author', etc.
Syntax
Result = Obj.[IDLffVideoRead::]GetMetadata([Key] [, /KEYS])
Return Value
Returns an array of strings listing the metadata for the key specified.
Arguments
Key
Set "Key" to a string value indicating the key for which you wish to retrieve metadata.
The following table lists the typpical metadata keys recognized by the IDL-supported video file formats. Other formats may have their own list of recognized metadata keys.
|
Key |
|---|
|
album |
|
artist |
|
comment |
|
copyright |
|
genre |
|
title |
Either the Key argument or the /KEYS keyword must be specified when calling ::GetMetadata.
::GetMetadata will error if the "key" you specify is not present in the file.
Keywords
KEYS
Set this keyword to return an array of all available metadata keys.
IDLffVideoRead::GetStreams
The ::GetStreams() method returns an array of structures describing the streams in the current file.
These structures are of the following format:
{
PID, ; Program ID - The internal identifier for the stream
TYPE, ; 0=unknown, 1=video, 2=audio, 3=data
RATE, ; Rate in Hertz. For example, 25 FPS for video, or 44100 Hz for audio
WIDTH, ; Video only. Width in pixels
HEIGHT, ; Video only. Height in pixels
CHANNELS, ; Audio only. Number of audio channels
CODEC, ; String identifying the codec used
LENGTH, ; Stream length in seconds
COUNT ; Number of frames of that stream in the file
}
Note: Animated GIF files do not contain header information on the frame rate, duration, or the number of frames. These values are estimated from other header information and may be incorrect.
Note: The LENGTH, COUNT, and RATE fields are best guess approximations given by the FFMPEG library. This is due to the reported RATE of some files being slightly different than the actual RATE. For example, an NTSC file might have a reported RATE of 30 but an actual RATE of 29.97. These differences vary by formats and codecs.
Syntax
Result = Obj.[IDLffVideoRead::]GetStreams()
Return Value
Returns an array of structures describing the current file's streams.
Arguments
None.
Keywords
None.
IDLffVideoRead::Seek
Repositions the current location in the file to as close as possible to the input time.
Syntax
Obj.[IDLffVideoRead::]Seek, Time
Return Value
None.
Arguments
Time
Desired position in the file, in seconds from the beginning.
Keywords
None.
IDLffVideoRead::Cleanup
This method closes the file and destroys the object.
Syntax
Obj.[IDLffVideoRead::]Cleanup
or
OBJ_DESTROY, Obj
Additional Example
Read in the same file as in our original example, above, and show the use of the ::GetMetadata method.
; Specify the file and create an IDLffVideoRead object
; to hold the file.
file = 'C:\Users\nrynes\IDLWorkspace82\CME.mp4'
oVid = OBJ_NEW('IDLffVideoRead', file)
; Obtain array of all available metadata for the file.
meta = oVid.GetMetadata(/KEYS)
HELP, meta
PRINT, meta
IDL displays:
META STRING = Array[5]
major_brand minor_version compatible_brands creation_time encoder
; Get and display some metadata based on the results above.
brand = oVid.GetMetadata("major_brand")
PRINT, brand
IDL displays:
mp42
Version History
|
8.2.3 |
Introduced |
|
8.3 |
Allow ::GetCodecs and ::GetFormats to be called as static methods. |
|
8.4 |
Added VERBOSE keyword to ::Init |
Resources and References
The NASA "CME.mp4" video used in the example is courtesy of the Solar Dynamics Observatory (SDO) and the Solar and Heliospheric Observatory (SOHO). The file is available for download here:
https://www.nasa.gov/multimedia/videogallery/index.html?media_id=160387251
A longer, similar video that can be substituted in the example code, is available for download here:
https://www.nasa.gov/mission_pages/sdo/news/coronal-rain.html
See Also
Creating Video, IDLffVideoWrite, OBJ_DESTROY, OBJ_NEW, QUERY_VIDEO, READ_VIDEO, WRITE_VIDEO